.\"
.\" Copyright (C) 1994-2021 Altair Engineering, Inc.
.\" For more information, contact Altair at www.altair.com.
.\"
.\" This file is part of both the OpenPBS software ("OpenPBS")
.\" and the PBS Professional ("PBS Pro") software.
.\"
.\" Open Source License Information:
.\"
.\" OpenPBS is free software. You can redistribute it and/or modify it under
.\" the terms of the GNU Affero General Public License as published by the
.\" Free Software Foundation, either version 3 of the License, or (at your
.\" option) any later version.
.\"
.\" OpenPBS is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Affero General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.\"
.\" Commercial License Information:
.\"
.\" PBS Pro is commercially licensed software that shares a common core with
.\" the OpenPBS software.  For a copy of the commercial license terms and
.\" conditions, go to: (http://www.pbspro.com/agreement.html) or contact the
.\" Altair Legal Department.
.\"
.\" Altair's dual-license business model allows companies, individuals, and
.\" organizations to create proprietary derivative works of OpenPBS and
.\" distribute them - whether embedded or bundled with other software -
.\" under a commercial license agreement.
.\"
.\" Use of Altair's trademarks, including but not limited to "PBS™",
.\" "OpenPBS®", "PBS Professional®", and "PBS Pro™" and Altair's logos is
.\" subject to Altair's trademark licensing policies.
.\"
.TH pbs_runjob 3B "15 November 2019" Local "PBS Professional"
.SH NAME
.B pbs_runjob
\- run a PBS batch job
.SH SYNOPSIS
#include <pbs_error.h>
.br
#include <pbs_ifl.h>
.sp
.nf
.B int pbs_runjob(int connect, char *jobID, char *location, 
.B \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ char *extend)
.fi
.SH DESCRIPTION
Issues a batch request to run a batch job.

Generates a
.I Run Job 
(15) request and sends it to the server over the connection specified by 
.I connect.  

If no file stagein is required, the server replies when the job has
started execution.  If file stagein is required, the server replies
when staging is started.

.SH REQUIRED PRIVILEGE
You must have Manager or Operator privilege to use this command.

.SH ARGUMENTS
.IP connect 8
Return value of 
.B pbs_connect().  
Specifies connection over which to send batch request to server.

.IP jobID 8
ID of job to be run.  
.br
Format for a job:
.br
.I <sequence number>.<server name>
.br
Format for a job array:
.br
.I <sequence number>[].<server name

.IP location 8
Location where job should run, and optionally resources to use.  Same as 
.B qrun -H:

.RS 8
.IP "-H <vnode specification without resources>" 3
The 
.I vnode specification without resources
has this format:
.br
.I \ \ \ (<vchunk>)[+(<vchunk>) ...]
.br
where 
.I vchunk 
has the format
.br
.I \ \ \ <vnode name>[+<vnode name> ...]
.br
Example: -H (VnodeA+VnodeB)+(VnodeC)

PBS applies one requested chunk from the job's selection directive in round-robin
fashion to each 
.I vchunk 
in the list.  Each 
.I vchunk 
must be sufficient to run the job's corresponding chunk, otherwise
the job may not execute correctly.
.RE

.RS 8
.IP "-H <vnode specification with resources>" 3
The 
.I vnode specification with resources
has this format:
.br
.I \ \ \ (<vchunk>)[+(<vchunk>) ...]
.br
where 
.I vchunk 
has the format
.IP "" 6
.I <vnode name>:<vnode resources>[+<vnode name>:<vnode resources> ...]
.LP
.RS 3
and where
.I vnode resources
has the format
.RS 3
<resource name>=<value>[:<resource name>=<value> ...]
.RE

.IP "Example:" 3
.nf
-H (VnodeA:mem=100kb:ncpus=1)+ 
.br 
     (VnodeB:mem=100kb:ncpus=2+ VnodeC:mem=100kb)
.fi
.LP

PBS creates a new selection directive from the 
.I vnode specification with resources, 
using it instead of the original specification from the user.
Any single resource specification results in the
job's original selection directive being ignored.  Each 
.I vchunk 
must be sufficient to run the job's corresponding chunk, otherwise
the job may not execute correctly.

If the job being run requests
.I -l place=exclhost,
take extra care to satisfy the 
.I exclhost 
request.  Make sure that if any vnodes are from a multi-vnoded host, 
all vnodes from that host are allocated.  Otherwise those vnodes can 
be allocated to other jobs.
.RE
.RE

.IP extend 8
Character string for extensions to command.  Not currently used.

.SH RETURN VALUE
The routine returns 0 (zero) on success.
.br

If an error occurred, the routine returns a non-zero exit value, and
the error number is available in the global integer 
.I pbs_errno.

.SH SEE ALSO
qrun(1B), pbs_asyrunjob(3B), pbs_connect(3B)
